.TH lha_daemonctl 1 "8 May 2012" "TrueCL Commands"

.SH NAME
lha_daemonctl \- Send messages to TrueCL daemons

.SH SYNOPSES
.TS
l l.
Cluster Daemon Interaction:

lha_daemonctl	\fB--daemon\fP \fIsyncd\fP|\fBlockd\fP|\fBhbd\fP|\fBclusterd\fP|\fBstatd\fP|\fBnetd\fP|\fBmond\fP
	\fB--msg\fP \fIMSG\fP [\fB--node\fP \fIN\fP] [\fB--timeout\fP \fIT\fP]
	[\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP] [\fB--lwidth\fP \fIW\fP]

Database Service Interaction:

lha_daemonctl	\fB--daemon\fP \fIcldb\fP|\fBclstatdb\fP
	\fB--msg\fP \fIMSG\fP [\fB--node\fP \fIN\fP] [\fB--timeout\fP \fIT\fP]
	[\fB--debug\fP|\fB--verbose\fP|\fB--quiet\fP|\fB--silent\fP] [\fB--lwidth\fP \fIW\fP]
.TE

.SH DESCRIPTION
The \fIlha_daemonctl(1)\fP command is used to send messages directly to TrueCL daemons
and prints the response. By default the message is sent to that particular daemon running
on the current host, though that can be modified by command line arguments.

It should be noted that it is unlikely you will actually need to use this function!
It has really been designed to aid debugging and problem diagnosis rather than 
being required for day-to-day administration or cluster modification.

.SH CAUTION!
There are a large number of commands that can be sent to various cluster daemons.
Only a few of those are listed here. Some of these may impair cluster performance
or stability. Where possible warnings will be given, though if in doubt please refrain
from using the command or a particular message.

.SH ARGUMENTS
.TP 8
--daemon
The name of the daemon that you wish to connect to.
.TP
--msg
The message to send to the daemon. If the message includes white space it should be
enclosed in quotes.
.TP
--node
The node to send to the message to. Defaults to the current node if not specified.
.TP
--timeout
The timeout to wait for a response. The default is 10 seconds.
.TP
--debug
Perform the actions and generate debug level output. This is not 
typically required and should only be done if problems in cluster 
management occur.
.TP
--verbose
Verbose mode generates a sensible amount of output to standard output to 
show the progress of the routine add/set or delete.
.TP
--quiet
This will only produce errors and warnings on the standard output device.
.TP
--silent
Only produce output if fatal errors occurs during application route 
management.
.TP
--lwidth
The width of the standard output. This will default to 80 if the width
of the standard output device cannot be determined. 

.SH CONFIG DATABASE SERVICE REQUESTS
.TP 12
PING
Check to see whether the database is up and running or not.
.TP
ABORT
Abort the current service process. Obviously will be restarted when needed.

.SH STATUS DATABASE SERVICE REQUESTS
.TP 12
PING
Check to see whether the database is up and running or not.

.TP
ABORT
Abort the current service process. Obviously will be restarted when needed.

.SH SYNC DAEMON (hbd) REQUESTS
This daemon is responsible for attempting to resynchronise storage
when the storage type in question is replicated. Many clusters will 
not make use of this daemon though it will always actually be started.

.TP 12
RESTART
Restart the process - used when the cluster software has been upgraded
in place.
.TP
ABORT
Abort the daemon.
.TP
PING
Return an "OK" message (used to check to see if the daemon is running and
responsive).
.TP
RECONFIGURE
Reread all configuration information. This will update all settings associated
with this daemon, but use the same running program.
.TP
RESET_ALL_ATTEMPTS
All devices which require possible resynchronisation will have the number
of attempted (and failed) requests reset to 0.
.TP
RESET_ATTEMPTS vgname lvname appname
Reset the number of unsuccessful attempts that are associated with 
trying to resynchronise the storage device in question. Normally TrueCL
will attempt several times and then give up. This will cause TrueCL to
attempt resynchronisation on the device again.
.TP
DUMP
This will dump out key structures from the latest synchronisation attempt.
If no synchronisation is necessary (since no such devices in use on 
applications running on the current node), a simple message indicating the
fact will be shown.

.SH LOCK DAEMON (hbd) REQUESTS
Locking is used sparingly in TrueCL though is an important aspect. The locking
daemon is very simple and thus supports only a few messages that the
\fBlha_daemonctl\fP routine can send to it.

.TP 12
RECONFIGURE
Reread all configuration information. This will update all settings associated
with locks. Note that any existing locks that are active are kept.
.TP
GET_LOCK lock host
Attempt to gain the necessary lock. This does not sleep if a lock is not
available but instead will return "ALREADY_LOCKED". Return values are "OK", 
"NOSUCHLOCK", "ALREADY_LOCKED" or "MISSING_ARG".
.TP
DROP_LOCK lock host
Drops the lock (if being held) for the host in question. Return values are 
"OK" or "NOSUCHLOCK".
.TP
ABORT
Aborts the daemon.
.TP
LIST_LOCKS
Returns summary informatino on the number of locks currently in use. The format of 
the response is:
.TS
l.
OK
appconfig=0/1 apprun=0/2 diskconfig=0/1 netconfig=0/1
.TE

In the above case the first number is the number active and the second is the
total number of those locks available.

.SH NETWORK DAEMON (netd) REQUESTS
.TP 12
RESTART
Stop all processes and restart everything. Since it re-executes all processes
it is more invasive than a reconfiguration (and can pick up changes to software
after an uprade for example).
.TP
RECONFIGURE
Re-read all configuration data and update processing as appropriate. Used when 
cluster changes and reconfigurations take place.
.TP
APP_ROUTE_PAUSE app route
Pause checking the particular route for the particular application.
.TP
APP_ROUTE_RESUME app route
Resume checking the particular route for the particular application.
.TP
TOPOLOGY_STATUS
Returns a summary of topology names and the current status of each 
on this host. 
.TP
DUMP
Dump out information on the internal status of the network daemon
(and child processes).
.TP
TOPOLOGY_RECHECK topology
If a topology is currently classed as inactive then sending this message
will cause the daemon to recheck (and mark as active if appropriate)
the topology again.
.TP
PING
Return an "OK" message (used to check to see if the daemon is running and
responsive).
.TP
ABORT
Abort the daemon and any associated child processes.
.TP
APP_STOP app
Sent if the application in question is stopping on this node. Any routes
for the child process are stopped when this request is received.
.TP
APP_RESTART app
Indicates the application in question has been restarted. Any route checks
associated with the application are stopped/started.
.TP
APP_START app
Indicates the specified application has just started on this node. Any
particular application route monitors associated with the application
will bw performed.

.SH MONITOR DAEMON (mond) REQUESTS
.TP 12
RECONFIGURE
Re-read all information regarding the core daemon characteristics
and also the monitoring requirements of all applications currently running on 
this node.
.TP
PING
Return an "OK" message (used to check to see if the daemon is running and
responsive).
.TP
GET_STATS
Get information regarding all currently running monitors associated with
this host. This will include a single line per monitor and outputs
monitors for applications and the host. The format of the output is:

.TS
l.
montype appname/monname type status interval failcount lastfailtime nextwakeup rearm
.TE

Where:
.RS 4
.TP
montype
The monitor type - will be 'A' for application, or 'N' for node.
.TP
appname
If the monitor type is 'A' then this is the name of the application for which
the monitor is being performed for.
.TP
monname
The name of the monitor - this is a label used to identify and manage the
monitor.
.TP
type
The type of the monitor. The monitors are available from the directories monitors/app and
monitors/node in the TrueCL installation directory.
.TP
status
The status of the check - '1' indicates the check is running and '0' that it has been
marked inactive.
.TP
interval
The number of seconds between performing the check.
.TP
failcount
The current number of failures registered for the check.
.TP
lastfailtime
The UNIX time of the last failure.
.TP
nextwakeup
The time when the next check will be performed.
.TP
rearm
The time after which the current failure count will be wiped and the monitor
considered 'clean'.

.RE
.TP 12
MON_STOP mon
Stop the specified monitor. The "mon" should be in the format "N:name" for a named
node monitor, or "A:app:monnam" for a monitor related to an application.
.TP
MON_START mon
Starts the specified monitor. The format of "mon" is as for "MON_STOP".
.TP
MON_RESET_FAILS mon
Changs the number of current fails associated with the monitor back to 0.
Also sets the rearm time to 00:00:00.
.TP
APP_STOP app
Indicates that the application is no longer running on this node and so 
all associated application monitors should be stopped.
.TP
APP_START app
This indicates that the specified application has started on this node and so
allow associated monitors for the application should be started.
.TP
RESTART
Performs a complete monitor restart. Useful if there have been software changes
and the cluster needs to restart the processes to pick up the changes.
.TP
DUMP
Dump out internal status information for the daemon.

.SH HEARTBEAT DAEMON (hbd) REQUESTS
.TP 12
RECONFIGURE
The heartbeat daemon and all child processes currently running will 
check the environment and reconfigure themselves. This is used if the
cluster is changed in any way.
.TP
STOPHB|name
Must be supplied with the name of a DISK heartbeat. It will stop generating
heartbeats on raw storage configured for this disk.
.TP
STARTHB|name
Starts writing messages again (following a stop) to this particular
disk heartbeat.
.TP
STATHB|file
Writes out details of all disk heartbeats to the named file. Notice that
the file must not exist and is written on the node when the message is sent to.
.TP
SET_NODE_LIST|N,N...
Sets the list of nodes that the heartbeat daemon will classify as listening
to requests that this local node is up and running.
.TP
GET_NODE_LIST
Returns the list of nodes that are known about and the time of the last 
responses received from them. The format of the response is:

.TS
l.
OK node=unixtime ...
.TE
The unixtime will include a fractional part too, and if set to -1 it indicates
no response has been heard from the node in question.
.TP
ALIVE|host
Indicates that the node in question is now (still) available. Typically sent from
peer heartbeat daemons.
.TP
DEAD|host,...
The node(s) specified have been classified as being dead and so heartbeat messages
do not need to be sent to them.
.TP
ADD_NODE|host
A new node has been added to the cluster configuration - so configure to send requests to it.
.TP
REMOVE_NODE|host
An existing node has been removed from the cluster configuration - remove references to it.
.TP
ABORT
Stop the heartbeat daemon on this node.
.TP
PAUSE
Stop checking the status of heartbeats - but continue to send them out to 
other nodes in the cluster.
.TP
RESUME
Check the responses from other nodes again looking for nodes that might be
considered dead.
.TP
DUMP
Dump out key statistics from the currently running process (and child processes).

.SH CLUSTER DAEMON (clusterd) REQUESTS
This is the core daemon behind most of TrueCL's automated functionality. Thus it is 
particularly important not to send requests to this daemon unless you really must - 
and understand the consequences of the request.

Note that the messages indicated here are when the cluster daemon is running in a 
steady state as part of a running cluster. A different set of messages are expected
during cluster formation/reformation and many of the requests below will simply be
discarded whilst the cluster daemon is attempting to join a cluster or form one.

.TP 12
RECONFIGURE
Re-read all information regarding the core daemon characteristics. This will also
cause re-probing for any running applications on this node.
.TP
PING
Return an "OK" message (used to check to see if the daemon is running and
responsive).
.TP
ABORT
Stop the daemon running. This should be used with caution since it leaves all
applications running, all other daemons running. In such cases the node will
still be considered as being part of the cluster but will not be able to respond
to most events that impact the cluster.
.TP
RESTART
Restart the cluster daemon. Like other RESTART requests this differs from a 
reconfiguration since the process is re-executed and thus will use the current
version of the program on the file system rather than just updating its configuration.
.TP
NEXTNODE appname
Returns the next node that would be used if this application were to fail. The results
may be dynamic if special perferred node settings were used for the application (such
as $$MOST_MEMORY).
.TP
CLPROTO submessage
This is the main type of request the cluster daemon responds to. There are many possible
sub-messages but these should not be used by end users - only the cluster daemons
when communicating with each other.
.TP
DUMP
Dump out information regarding internal data structures. Used for debugging and
production support.

.SH EXIT CODES
If the attempt to query the node in question is successful a value of '0' will be returned. 
Any other value indicates failure to communicate to the node. Whether the actual request
to perform or not was successful is not determined by the return value.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2012, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR clreq(1),
.BR lha_clusterd(1),
.BR lha_hbd(1),
.BR lha_lockd(1),
.BR lha_mond(1),
.BR lha_netd(1),
.BR lha_statd(1),
.BR lha_syncd(1),
.BR lha_netd(1).

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

